Create Outgoing Webhooks

The Outgoing Webhook acts as a bot and searches for messages in channels using @mention. It sends notifications to an external web service and responds with rich messages, which include cards and images. It helps to skip the process of creating bots through the Microsoft Bot Framework.

Key features of Outgoing Webhooks

The following table provides the features and description of Outgoing Webhooks:

Features	Description
Scoped configuration	Webhooks are scoped at the team level. Mandatory setup process for each adds an Outgoing Webhook.
Reactive messaging	Users must use @mention for the webhook to receive messages. The users can only message an Outgoing Webhook in public channels and not within the personal or private scope.
Standard HTTP message exchange	Responses appear in the same chain as the original request message and can include any Bot Framework message content. For example, rich text, images, cards, and emojis. Although Outgoing Webhooks can use cards, they can't use any card actions except for openURL.
Teams API method support	Outgoing Webhooks sends an HTTP POST to a web service and gets a response. They can't access any other APIs, such as retrieve the roster or list of channels in a team.

Create Outgoing Webhooks

Create Outgoing Webhooks and add custom bots to Teams. To create an Outgoing Webhook, follow these steps:

1. Select Teams from the left pane.

   

2. In the Teams page, select the required team to create an Outgoing Webhook and select •••.

3. Select Manage team from the dropdown menu.

   

4. Select Apps on the channel page.

   

5. Under Upload an app, select Create an outgoing webhook.

   

6. Type the following details in the Create an outgoing webhook page:

   • Name: The webhook title and @mention tab.
   • Callback URL: The HTTPS endpoint that accepts JSON payloads and receives POST requests from Teams.
   • Description: A detailed string that appears in the profile card and the team-level app dashboard.
   • Profile picture: An app icon for your webhook, which is optional.

7. Select Create. The Outgoing Webhook is added to the team's channel.

   

A Hash-based Message Authentication Code (HMAC) dialogue appears. It's a security token used to authenticate calls between Teams and the designated outside service. The HMAC security token doesn't expire and is unique for each configuration.

Note

The Outgoing Webhook is available to the team's users, only if the URL is valid and the server and client authentication tokens are equal. For example, an HMAC handshake.

The following scenario provides the details to add an Outgoing Webhook:

• Scenario: Push change status notifications on a Teams channel database server to your app.
• Example: You have a custom app built for your org (LOB app) that tracks all CRUD (create, read, update, and delete) operations. These operations are made to the employee records by Teams channel HR users across a Microsoft 365 tenancy.

URL JSON payload

Create a URL on your app's server to accept and process a POST request with a JSON payload

Your service receives messages in a standard Azure bot service messaging schema. The Bot Framework connector is a RESTful service that empowers to process the interchange of JSON formatted messages through HTTPS protocols as documented in the Azure Bot Service API. Alternatively, you can follow the Microsoft Bot Framework SDK to process and parse messages. For more information, see overview of Azure Bot Service.

Outgoing Webhooks are scoped to the team level and are visible to all the team members. Users need to @mention the name of the Outgoing Webhook to invoke it in the channel.

Verify HMAC token

Create a method to verify the Outgoing Webhook HMAC token

Using example of inbound message and ID: "contoso" of SigningKeyDictionary of {"contoso", "vqF0En+Z0ucuRTM/01o2GuhMH3hKKk/N2bOmlM31zaA=" }.

Use the value "HMAC 03TCao0i55H1eVKUusZOTZRjtvYTs+mO41mPL+R1e1U=" in the authorization of request header.

To ensure that your service is receiving calls only from actual Teams clients, Teams provides an HMAC code in the HTTP hmac authorization header. Always include the code in your authentication protocol.

Your code must always validate the HMAC signature included in the request as follows:

• Generate the HMAC token from the request body of the message. There are standard libraries to do this on most platform, such as Crypto for Node.js and Teams webhook sample for C#. Microsoft Teams uses standard SHA256 HMAC cryptography. You must convert the body to a byte array in UTF8.
• Compute the hash from the byte array of the security token provided by Teams when you registered the Outgoing Webhook in the Teams client. See create an Outgoing Webhook.
• Convert the hash to a string using UTF-8 encoding.
• Compare the string value of the generated hash with the value provided in the HTTP request.

Sample code reference

public static AuthResponse Validate(AuthenticationHeaderValue authenticationHeaderValue, string messageContent, string claimedSenderId)
{
    //...
    string providedHmacValue = authenticationHeaderValue.Parameter;
    string calculatedHmacValue = null;
    try
    {
        byte[] serializedPayloadBytes = Encoding.UTF8.GetBytes(messageContent);
 
        byte[] keyBytes = Convert.FromBase64String(signingKey);
        using (HMACSHA256 hmacSHA256 = new HMACSHA256(keyBytes))
        {
            byte[] hashBytes = hmacSHA256.ComputeHash(serializedPayloadBytes);
            calculatedHmacValue = Convert.ToBase64String(hashBytes);
        }
 
        if (string.Equals(providedHmacValue, calculatedHmacValue))
        {
            return new AuthResponse(true, null);
        }
        else
        {
            string errorMessage = string.Format(
                "AuthHeaderValueMismatch. Expected:'{0}' Provided:'{1}'",
                calculatedHmacValue,
                providedHmacValue);
 
            return new AuthResponse(false, errorMessage);
        }
    }
    catch (Exception ex)
    {
        Trace.TraceError("Exception occurred while verifying HMAC on the incoming request. Exception: {0}", ex);
        return new AuthResponse(false, "Exception thrown while verifying MAC on incoming request.");
    }
}

Method to respond

Create a method to send a success or failure response

Responses from your Outgoing Webhooks appear in the same reply chain as the original message. When the user performs a query, Teams issues a synchronous HTTP request to your service and your code gets five seconds to respond to the message before the connection times out and terminates.

Example response

{
    "type": "message",
    "text": "This is a reply!"
}

Use Adaptive Cards with Outgoing Webhooks

You can send Adaptive Card, Hero card, and text messages as attachment with an Outgoing Webhook. Cards support formatting. For more information, see format cards with Markdown. Adaptive Card in Outgoing Webhooks supports only openURL card actions.

The following codes are examples of an Adaptive Card response:

C#/.NET

Sample code reference

// This method is to read the request body content
string content;
using (var reader = new StreamReader(Request.Body))
    {
        content = await reader.ReadToEndAsync();
    }

var Card = new AdaptiveCard(new AdaptiveSchemaVersion("1.4"))
{
    Body = new List<AdaptiveElement>()
    {
        new AdaptiveTextBlock(){Text= $"Request sent by: {incomingActivity.From.Name}"},
        new AdaptiveImage(){Url=new Uri("https://c.s-microsoft.com/en-us/CMSImages/DesktopContent-04_UPDATED.png?version=43c80870-99dd-7fb1-48c0-59aced085ab6")},
        new AdaptiveTextBlock(){Text="Sample image for Adaptive Card.."}
    }
};

var attachment = new Attachment()
{
    ContentType = AdaptiveCard.ContentType,
    Content = Card
};

var sampleResponseActivity = new Activity
{
    Attachments = new [] { attachment }
};

return sampleResponseActivity;

JavaScript/Node.js

Sample code reference

var receivedMsg = JSON.parse(payload);
var responseMsg = JSON.stringify({
    "type": "message",
    "attachments": [
        {
            "contentType": "application/vnd.microsoft.card.adaptive",
            "contentUrl": null,
            "content": {
                "type": "AdaptiveCard",
                "version": "1.4",
                "body": [
                    {
                        "type": "TextBlock",
                        "text": "Request sent by: " + receivedMsg.from.name
                    },
                    {
                        "type": "Image",
                        "url": "https://c.s-microsoft.com/en-us/CMSImages/DesktopContent-04_UPDATED.png?version=43c80870-99dd-7fb1-48c0-59aced085ab6"
                    },
                    {
                        "type": "TextBlock",
                        "text": "Sample image for Adaptive Card."
                    }
                ]
            },
            "name": null,
            "thumbnailUrl": null
        }
    ]
});

JSON

{
 "type": "message",
 "attachments": [
  {
   "contentType": "application/vnd.microsoft.card.adaptive",
   "content": {
    "type": "AdaptiveCard",
    "version": "1.4",
    "body": [
     {
      "type": "TextBlock",
      "text": "Request sent by: Megan"
     },
     {
      "type": "Image",
      "url": "https://c.s-microsoft.com/en-us/CMSImages/DesktopContent-04_UPDATED.png?version=43c80870-99dd-7fb1-48c0-59aced085ab6"
     },
     {
      "type": "TextBlock",
      "text": "Sample image for Adaptive Card.."
     }
    ]
   }
  }
 ]
}

Code sample

Sample name	Description	.NET	Node.js
Outgoing Webhooks	This sample shows how to implement and use outgoing webhook.	View	View

Step-by-step guide

Follow the step-by-step guide to create Outgoing Webhooks in Teams.

See also

• Webhooks and connectors
• Create and send messages
• Create Incoming Webhooks
• Create connectors for Microsoft 365 Groups
• Adaptive Cards